Cogito: Cleanup documentation building and add quick reference
Hi,
Here are a few patches that makes it possible to build documentation as PDF using docbook2pdf (chosen because xmlto doesn't seem to be able to generate PDFs).
All the patches leads up to adding a quick reference with often used Cogito commands and associated option. It is inspired by svn-ref and the goal is to have the PDF version under two pages long. The grouping of commands could need some more comments.
The quick reference can be translated into HTML, PDF and cg-ref(7) manpage. The last one is achieved by stripping much of the markup from the 'default' version since manpages cannot have table layout. Note the HTML and PDF versions are generated as quick-reference.{html,pdf}. We might want to generate cg-ref.{html,pdf} instead.
Signature · 1 line
Jonas Fonseca
PATCH 1/4 Simplify wildcards for match files to be ignored
---
Documentation/Makefile | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-)
Documentation/Makefile +1 -1
@@ -1,4 +1,4 @@ -CG_IGNORE=$(wildcard ../cg-X* ../cg-*.orig ../cg-*.rej ../cg-*.in) +CG_IGNORE=$(wildcard ../cg-X* ../cg-*.*) CG_SRC=$(filter-out $(CG_IGNORE), $(wildcard ../cg*)) PACKAGE=cogito
Signature · 1 line
Jonas Fonseca
Re: [PATCH 1/4] Simplify wildcards for match files to be ignored
Quoted 12 lines · Jonas Fonseca
Signed-off-by Jonas Fonseca <[email protected]>---
Documentation/Makefile | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-)Documentation/Makefile +0
-0
Documentation/Makefile line 1
Quoted 2 lines
Documentation/Makefile +1
-1@@ -1,4 +1,4 @@ -CG_IGNORE=$(wildcard ../cg-X* ../cg-*.orig ../cg-*.rej ../cg-*.in) +CG_IGNORE=$(wildcard ../cg-X* ../cg-*.*)
Nope. Better be specific in what you delete. It is not exactly performance-critical...
Signature · 4 lines
Dr. Horst H. von Brand User #22616 counter.li.org Departamento de Informatica Fono: +56 32 654431 Universidad Tecnica Federico Santa Maria +56 32 654239 Casilla 110-V, Valparaiso, Chile Fax: +56 32 797513
Re: [PATCH 1/4] Simplify wildcards for match files to be ignored
Horst von Brand <[email protected]> wrote Fri, Mar 10, 2006:
Quoted 8 lines
Quoted 7 lines · Jonas Fonseca
Signed-off-by Jonas Fonseca <[email protected]>---
Documentation/Makefile | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-)
Quoted 10 lines
Documentation/Makefile line 1
Quoted 7 lines
Documentation/Makefile +1
-1@@ -1,4 +1,4 @@ -CG_IGNORE=$(wildcard ../cg-X* ../cg-*.orig ../cg-*.rej ../cg-*.in) +CG_IGNORE=$(wildcard ../cg-X* ../cg-*.*)Nope. Better be specific in what you delete. It is not exactly performance-critical...
The intention was to ignore also cg-*.patch, but then ignoring any file with a dot in makes sense and avoids a lot more errors when building documentation in a dirty tree.
Signature · 1 line
Jonas Fonseca
PATCH 2/4 Encode the manpage section in the file name
In reply to Jonas FonsecaThis makes it easier to handle other document types.
---
Documentation/Makefile | 39 +++++++++++++++++++++++++++------------ 1 files changed, 27 insertions(+), 12 deletions(-)
Documentation/Makefile +27 -12
@@ -3,13 +3,13 @@ CG_SRC=$(filter-out $(CG_IGNORE), $(wild PACKAGE=cogito -MAN1_TXT=$(patsubst ../cg%,cg%.txt,$(CG_SRC)) -MAN7_TXT=$(PACKAGE).txt +MAN1_TXT=$(patsubst ../cg%,cg%.1.txt,$(CG_SRC)) +MAN7_TXT=$(PACKAGE).7.txt DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) introduction.html -DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT)) -DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) +DOC_MAN1=$(patsubst %.txt,%,$(MAN1_TXT)) +DOC_MAN7=$(patsubst %.txt,%,$(MAN7_TXT)) prefix=$(HOME) bin=$(prefix)/bin
@@ -56,28 +56,43 @@ install-html: html $(INSTALL) $(DOC_HTML) $(DESTDIR)/$(htmldir) clean: - rm -f *.xml *.html *.1 *.7 cg*.txt $(PACKAGE).txt + rm -f *.xml *.html *.1 *.7 cg*.[17].txt $(PACKAGE).7.txt .PRECIOUS: cg%.txt introduction.html: ../README asciidoc -b xhtml11 -d article -f asciidoc.conf -o $@ $< -%.html : %.txt +%.1.html : %.1.txt asciidoc -b xhtml11 -d manpage -f asciidoc.conf $< -%.1 %.7 : %.xml - xmlto man $< +%.7.html : %.7.txt + asciidoc -b xhtml11 -d manpage -f asciidoc.conf $< -%.xml : %.txt +%.html : %.txt + asciidoc -b xhtml11 -d article -f asciidoc.conf -o $@ $< + +%.1.xml : %.1.txt asciidoc -b docbook -d manpage -f asciidoc.conf $< -$(PACKAGE).txt : make-$(PACKAGE)-asciidoc +%.7.xml : %.7.txt + asciidoc -b docbook -d manpage -f asciidoc.conf $< + +%.xml : %.txt + asciidoc -b docbook -d article -f asciidoc.conf $< + +%.1 : %.1.xml + xmlto man $< + +%.7 : %.7.xml + xmlto man $< + +$(PACKAGE).7.txt : make-$(PACKAGE)-asciidoc ./make-$(PACKAGE)-asciidoc > $@ # It seems that cg%.txt won't match this so use an explicit rule -cg.txt : ../cg make-cg-asciidoc +cg.1.txt : ../cg make-cg-asciidoc CGPACKAGE=$(PACKAGE) ./make-cg-asciidoc $< > $@ -cg-%.txt : ../cg-% make-cg-asciidoc +cg-%.1.txt : ../cg-% make-cg-asciidoc CGPACKAGE=$(PACKAGE) ./make-cg-asciidoc $< > $@
Signature · 1 line
Jonas Fonseca
PATCH 3/4 Generate PDF documents using docbook2pdf
In reply to Jonas FonsecaUnfortunately xmlto cannot be used for this,
---
Documentation/Makefile | 14 ++++++++++++-- 1 files changed, 12 insertions(+), 2 deletions(-)
Documentation/Makefile +12 -2
@@ -11,6 +11,8 @@ DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_ DOC_MAN1=$(patsubst %.txt,%,$(MAN1_TXT)) DOC_MAN7=$(patsubst %.txt,%,$(MAN7_TXT)) +DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) introduction.pdf + prefix=$(HOME) bin=$(prefix)/bin mandir=$(prefix)/man
@@ -35,15 +37,17 @@ all: html man txt html: $(DOC_HTML) - man: man1 man7 man1: $(DOC_MAN1) man7: $(DOC_MAN7) +pdf: $(DOC_PDF) + txt: txt1 txt7 txt1: $(MAN1_TXT) txt7: $(MAN7_TXT) + install: man txt $(INSTALL) -m755 -d $(DESTDIR)/$(txtdir) $(INSTALL) $(MAN1_TXT) $(MAN7_TXT) $(DESTDIR)/$(txtdir)
@@ -56,13 +60,16 @@ install-html: html $(INSTALL) $(DOC_HTML) $(DESTDIR)/$(htmldir) clean: - rm -f *.xml *.html *.1 *.7 cg*.[17].txt $(PACKAGE).7.txt + rm -f *.xml *.html *.pdf *.1 *.7 cg*.[17].txt $(PACKAGE).7.txt .PRECIOUS: cg%.txt introduction.html: ../README asciidoc -b xhtml11 -d article -f asciidoc.conf -o $@ $< +introduction.xml: ../README + asciidoc -b docbook -d article -f asciidoc.conf -o $@ $< + %.1.html : %.1.txt asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
@@ -87,6 +94,9 @@ introduction.html: ../README %.7 : %.7.xml xmlto man $< +%.pdf : %.xml + docbook2pdf $< + $(PACKAGE).7.txt : make-$(PACKAGE)-asciidoc ./make-$(PACKAGE)-asciidoc > $@
Signature · 1 line
Jonas Fonseca
PATCH 4/4 Add quick reference
In reply to Jonas Fonseca---
If someone wants to have a look, I've put it here:
http://www.diku.dk/hjemmesider/studerende/fonseca/cg-ref.pdf
Documentation/Makefile | 9 ++- Documentation/asciidoc.conf | 4 + Documentation/make-cg-ref-asciidoc | 61 +++++++++++++++++++ Documentation/quick-reference.txt | 114 ++++++++++++++++++++++++++++++++++++ 4 files changed, 185 insertions(+), 3 deletions(-)
Documentation/Makefile +6 -3
@@ -4,14 +4,14 @@ CG_SRC=$(filter-out $(CG_IGNORE), $(wild PACKAGE=cogito MAN1_TXT=$(patsubst ../cg%,cg%.1.txt,$(CG_SRC)) -MAN7_TXT=$(PACKAGE).7.txt +MAN7_TXT=$(PACKAGE).7.txt cg-ref.7.txt -DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) introduction.html +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) quick-reference.html introduction.html DOC_MAN1=$(patsubst %.txt,%,$(MAN1_TXT)) DOC_MAN7=$(patsubst %.txt,%,$(MAN7_TXT)) -DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) introduction.pdf +DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) quick-reference.pdf introduction.pdf prefix=$(HOME) bin=$(prefix)/bin
@@ -100,6 +100,9 @@ introduction.xml: ../README $(PACKAGE).7.txt : make-$(PACKAGE)-asciidoc ./make-$(PACKAGE)-asciidoc > $@ +cg-ref.7.txt : quick-reference.txt make-cg-ref-asciidoc + CGPACKAGE=$(PACKAGE) ./make-cg-ref-asciidoc $< > $@ + # It seems that cg%.txt won't match this so use an explicit rule cg.1.txt : ../cg make-cg-asciidoc CGPACKAGE=$(PACKAGE) ./make-cg-asciidoc $< > $@
Documentation/asciidoc.conf +4 -0
@@ -19,3 +19,7 @@ ifdef::backend-xhtml11[] [gitlink-inlinemacro] <a href="{target}.html">{target}{0?({0})}</a> endif::backend-xhtml11[] + +[attributes] +# Five non breaking spaces used for option indentation in the quick reference +cg-refopt=     
Documentation/make-cg-ref-asciidoc new file +61 -0
61 lines not on this page · raw message
Documentation/quick-reference.txt new file +114 -0
114 lines not on this page · raw message
Signature · 1 line
Jonas Fonseca
PATCH 4/4 Add quick reference
---
This renames quick-reference.txt to cg-ref.txt to address the cg-ref.pdf issue, makes the script more robust by using printf for alignment, and improves the reference itself a bit.
Documentation/Makefile | 9 ++- Documentation/asciidoc.conf | 4 + Documentation/cg-ref.txt | 116 ++++++++++++++++++++++++++++++++++++ Documentation/make-cg-ref-asciidoc | 70 ++++++++++++++++++++++ 4 files changed, 196 insertions(+), 3 deletions(-)
Documentation/Makefile +6 -3
@@ -4,14 +4,14 @@ CG_SRC=$(filter-out $(CG_IGNORE), $(wild PACKAGE=cogito MAN1_TXT=$(patsubst ../cg%,cg%.1.txt,$(CG_SRC)) -MAN7_TXT=$(PACKAGE).7.txt +MAN7_TXT=$(PACKAGE).7.txt cg-ref.7.txt -DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) introduction.html +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) cg-ref.html introduction.html DOC_MAN1=$(patsubst %.txt,%,$(MAN1_TXT)) DOC_MAN7=$(patsubst %.txt,%,$(MAN7_TXT)) -DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) introduction.pdf +DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) cg-ref.pdf introduction.pdf prefix=$(HOME) bin=$(prefix)/bin
@@ -100,6 +100,9 @@ introduction.xml: ../README $(PACKAGE).7.txt : make-$(PACKAGE)-asciidoc ./make-$(PACKAGE)-asciidoc > $@ +cg-ref.7.txt : cg-ref.txt make-cg-ref-asciidoc + CGPACKAGE=$(PACKAGE) ./make-cg-ref-asciidoc $< > $@ + # It seems that cg%.txt won't match this so use an explicit rule cg.1.txt : ../cg make-cg-asciidoc CGPACKAGE=$(PACKAGE) ./make-cg-asciidoc $< > $@
Documentation/asciidoc.conf +4 -0
@@ -19,3 +19,7 @@ ifdef::backend-xhtml11[] [gitlink-inlinemacro] <a href="{target}.html">{target}{0?({0})}</a> endif::backend-xhtml11[] + +[attributes] +# Five non breaking spaces used for option indentation in the quick reference +cg-refopt=     
Documentation/cg-ref.txt new file +116 -0
116 lines not on this page · raw message
Documentation/make-cg-ref-asciidoc new file +70 -0
70 lines not on this page · raw message
Signature · 1 line
Jonas Fonseca